perm filename INTERF.DOC[SYS,HE] blob
sn#144675 filedate 1975-02-07 generic text, type C, neo UTF8
COMMENT ⊗ VALID 00016 PAGES
C REC PAGE DESCRIPTION
C00001 00001
C00003 00002 1 10/11 INTERFACE - INTRODUCTION
C00007 00003 2 LOADING MON11
C00011 00004 3 INITIALIZATION AND CONTROL
C00015 00005 4 MONITOR COMMANDS - BLKCOM
C00019 00006 5 BLKCOM (cont)
C00022 00007 6 REPACK, RESET
C00026 00008 7 FNDBLK, errors
C00028 00009 8 USER COMMAND TRANSMISSION - SNDCOM, COMRET
C00031 00010 9 DATA TRANSMISSION - SNDPIC
C00035 00011 10 PUTBLK, GETBLK, GETWRD, PUTWRD
C00039 00012 11 ERRORS - INTERFACE AND PDP-11
C00041 00013 12 SPS-41 ERRORS
C00043 00014 13 USER COMMANDS
C00045 00015 14 TRACK FEATURES
C00053 00016 17 TRACK FEATURES (cont.)
C00057 ENDMK
C⊗;
1 10/11 INTERFACE - INTRODUCTION
by K. Pingle
This document describes a group of SAIL callable subroutines
which allow the user to run the MON11 program on the PDP11. These
subroutines can be loaded by requiring INTERF.REL[11,KKP] as a load
module in the calling program.
MON11 is a monitor program for the PDP11 which was written to
accept commands from the subroutines in INTERF. It is the only
program which INTERF can run. It contains an internal data structure
composed of variable length blocks of memory, refered to hereafter as
data blocks. These blocks can be created at the request of the user,
or possibly by some of the user commands to MON11. The user can
cause the transfer of data between these data blocks and his program,
as well as delete them. The user can also send commands to MON11 to
be executed. Currently there are three 'monitor' commands which
manipulate the data blocks. There are also various 'user' commands,
which cause MON11 to execute programs which process the data given to
it for the user. The subroutines in INTERF will send MON11 any
command you give it, but MON11 will only execute those it recognizes.
Subroutines which send commands to MON11 will wait until it
is ready to execute a new command before sendinig the command. The
monitor commands will return to the user when the command has been
executed. The user commands return as soon as the command has been
accepted by MON11. The user can continue his program and check later
for completion of the command. Subroutines which transmit data
between the two programs do not communicate directly with MON11.
They take control of the 11's memory away from MON11 and force the
transfer, then give control back to the 11, which, hopefully, will
not be upset by finding that its world has changed. Subroutines
which transfer more than one word of data give the user the option of
releasing the 11 between each word, or only when the entire transfer
is finished. The PDP10 programs will not notice any difference in
speed between the two options, but releasing 11 memory between each
transfer allows the 11 program to continue running, at a somewhat
reduced speed, while the tranfer proceeds. This allows the user to
fill one data block while MON11 is processing another one. Filling
the data block that is being processed is dangerous and considered
bad form.
2 LOADING MON11
MON11 must be loaded and running on the 11 before your
program on the 10 tries to use it. It can be loaded by system
program 11TTY. After starting it, type N if you do not want the
debugger loaded, L if you do. When it askes for a BIN file type
MON11n[SYS,HE]<cr>, where n is the version letter. Then type
S200<cr> if the debugger is loaded; S<cr> otherwise. MON11 will
initialize itself and then type out its name on the 11 console
teletype to let you know what version you have. If there is more
than one version, they will differ in which user commands they
recognize. The description of the user commands will tell which
version you need for the comands you want. The first time it is
started, MON11 will also type out the number of bytes of free storage
available to it. One half this number is the number of words
available for data blocks. It may not be very large if the debugger
is loaded.
3 INITIALIZATION AND CONTROL
DECLARATION: EXTERNAL PROCEDURE INIT11
This subroutine restarts MON11, causing it to lose all its
data structures, and puts the SPS-41 into a state which will allow
the 11 to control it. It should be called before executing any other
subroutine in this package to make certain the 11 is there,
especially if you just stopped you program in the middle and
restarted it. If any of the other subroutines discover that they
cannot communicate with the 11, they will type an error message
describing how they lost (see list which appears later in this
document), followed by:
type <CR> for automatic restart of PDP11
If a restart would hurt you, you will have to restart everything
yourself. If your program can survive a restart of the 11 only, type
<CR> and INIT11 will be called with the message:
attempting to reinitialize PDP11 -
INIT11 cannot alway force the 11 into a good state, as the hardware
interface is not finished yet. It will try and respond with either
'WE WON' (and return to the subroutine which called it) or type:
WE LOST - restart manually
and call the system. What you do then is up to you. I would suggest
you first try restarting MON11 at location 1000 (octal) and continue
your job on the 10, which will cause INIT11 to try again. If it
still fails you will have to reload MON11.
* * * * * * * * * * * * * *
DECLARATION: EXTERNAL BOOLEAN PROCEDURE IOWAIT(INTEGER COUNT)
IOWAIT waits for MON11 to acknowledge that it is ready to
accept more commands. Most of the subroutines which process commands
call this subroutine. You can too, but COMRET will probably be more
useful to you. COUNT is the number of ticks (1/60 second) that
IOWAIT will wait. The value of the subroutine is TRUE if MON11 is
ready; FALSE if it timed out.
4 MONITOR COMMANDS - BLKCOM
DECLARATION: EXTERNAL INTEGER PROCEDURE BLKCOM(INTEGER NEW_ID,
OLD_ID, SIZE; REFERENCE INTEGER ADDRESS);
This command creates and deletes data blocks for you. All
data blocks are referenced by an ID, which can be any integer greater
than zero and less than 2↑16. This ID is associated with only one
data block. The ID and the length of the block are constant. The
address of the block is variable, since this subroutine (and
possible certain user commands) will force a garbage collection of
the data structure if there is not enough space for the block to be
created.
The arguments to the command are all integers and contain the
following:
NEW_ID is the ID to be associated with the data block being created.
If NEW_ID≤0, no new data block will be created; only deletion
is possible.
OLD_ID is the ID of a currently existing data block which is to be
deleted. If OLD_ID≤0, the is no old block and a new block
will be created and added to the data structure. If OLD_ID
>0, and is not the size specified for NEW_ID, or NEW_ID≤0,
it will be deleted before the new block, if any, is created.
If both arguments are greater than zero and OLD_ID is the
size specified for NEW_ID, it will be renamed. In any case,
unless there is an error, OLD_ID will cease to exist, its
data will no longer be available if it was deleted, and the
ID which was in OLD_ID is available for reuse. If OLD_ID was
just renamed, the data which was in OLD_ID is now available
in NEW_ID. Newly created blocks have garbage in them until
filled by some other routine.
SIZE is the number of words the data block is to contain. Note
that the data block may contain up to two more words than
specified.
ADDRESS the subroutine returns here the address, in the 11, of the
first word of the block or zero if no block was created. This
address must be given to the data transmission routines. If a
garbage collection occurs after this data block is created,
and previously created blocks have been deleted, this address
is no longer valid. Use the FNDBLK command to update the
address.
5 BLKCOM (cont)
To summarize the effect of various states of NEW_ID and OLD_ID:
NEW_ID OLD_ID also causes
...... ...... ............ .............................
≤0 ≤0 no-op
≤0 >0 ∃ OLD_ID OLD_ID is deleted
any >0 ¬∃ OLD_ID same as though OLD_ID=0
>0 ≤0 ¬∃ NEW_ID NEW_ID is created **
>0 any ∃ NEW_ID ∧ same as though NEW_ID=0
OLD_ID≠NEW_ID
>0 >0 SIZE≠length OLD_ID is deleted, if it exists.
of OLD_ID Then NEW_ID is created if it does
not currently exist. **
>0 >0 SIZE=length of OLD_ID is renamed to NEW_ID
OLD_ID
** if any blocks have been deleted, these actions may cause a garbage
collection which can change the addresses of all data blocks which
were created after the creation of the oldest block which was
deleted.
The value of the subroutine is a status word in which error
bits are ORed together to tell you what, if anything, went wrong.
Fatal errors mean no data block was created (ADDRESS will be 0).
If only warning bits appear,a block was created if you asked for one.
The bits are: (octal)
0 If 0 is returned, there were no errors of any kind.
1 not enough room in 11 memory for new block (fatal)
2 block length was ≤0 and you wanted to create a block (fatal)
4 NEW_ID already exists, and NEW_ID≠OLD_ID (fatal)
10 OLD_ID does not exist. Command executed as though OLD_ID=0.
(warning)
20 OLD_ID=NEW_ID≤0. This is a lengthy no-op (warning)
6 REPACK, RESET
REPACK -
Sending command number 4 to SNDCOM, explained below, will
execute the REPACK command. This command repacks TV pictures stored
in the 11 to reduce their size. Since 11 memory is small at the
moment. This is an important operation. This allows you to send a
full picture to the 11, process it to find the parts you need for
further work, and then repack it to eliminate the fringes of the
picture and leave room for other pictures or data blocks. The
argument given to SNDCOM is the ID of the data block containing the
parameters for the command, which are:
WORD PARAMETER
1 ID of the picture data block to be repacked
2 new X coordinate of the left side of the picture
3 new Y coordinate of the top of the picture
4 new number of samples per line
5 new number of lines
The specified picture will be found and the rectangle
specified by the parameters will be extracted and placed at the front
of the picture block. Any space at the end of the block which is no
longer needed will be returned to free storage. When the COMRET
procedure is executed, this command will return as its data the new
size, in words, of the picture block and an error number decoded as
follows:
-2 did not find the picture data block
-1 did not find the parameter data block
0 ok - picture has been repacked
1 the new picture limits are outside the old limits
RESET -
Sending command number 0 to SNDCOM, explained below, will
execute the RESET command in MON11. It has the same effect as INIT11
if MON11 is waiting for a command, but it much gentler and faster. If
MON11 is really messed up and not waiting for a command, this will
have no effect. Do not call COMRET to wait for completion as MON11
will have forgotten all about it. IOWAIT will tell you if the reset
happened. This command is mainly for internal use. Be warned.
7 FNDBLK, errors
DECLARATION: EXTERNAL PROCEDURE FNDBLK(INTEGER ID;
REFERENCE INTEGER ADDR, SIZE)
Block ID is found, if it exists. Its size is returned in SIZE
and its current address in ADDR. If it does not exist, SIZE=ADDR=0.
* * * * * * * * * * * * * *
The monitor commands given above can generate many error
messages. See section on INTERFACE ERRORS below for most of them.
The following are unique to monitor commands:
PDP11 did not respond to command
MON11 did not signal end of command execution within 10 ticks.
PDP11 responded to wrong command
MON11 did not execute correct command.
After either of them, you can type <CR> to retry the command. Both of
these messages may signal either a hardware or software error in the
11. If they occur, check the 11's console TTY for error messages for
MON11 and report the details to me.
8 USER COMMAND TRANSMISSION - SNDCOM, COMRET
In addition to maintaining its data structure, MON11 also
executes various programs to process the data. These may vary,
depending on which version of the monitor you are running. The list
of user commands is given later. These routine transmit the commands
to MON11 and signal the end of their execution.
DECLARATION: EXTERNAL PROCEDURE SNDCOM(INTEGER COM, ARG)
SNDCOM send command COM and argument ARG to MON11. It
assumes that MON11 is ready to accept commands and returns as soon as
the command has been transmitted. It does not wait for command
completion. The command is a small positive integer. Use only the
integers listed with the descriptions of the user commands; the
others may be monitor commands. ARG is either the argument, for
commands with only one argument, or the ID of the data block
containing the arguments. Such data blocks must, of course, have
already been created and filled.
* * * * * * * * * * * * * * * *
DECLARATION: EXTERNAL BOOLEAN PROCEDURE COMRET(INTEGER TICKS;
REFERENCE INTEGER COMMAND, DATA, ERROR)
COMRET calls IOWAIT to wait TICKS ticks for the last command
given to finish. If IOWAIT times out, COMRET is FALSE; it is TRUE
otherwise. If the command finished, the output from MON11 is placed
in COMMAND, DATA, and ERROR. COMMAND is the command number which was
executed. If it is -1, MON11 did not recognize the command and the
other arguments are garbage, as nothing was executed. The contents
of DATA and ERROR are described under each user command. Normally
DATA is the result, if it will fit in one word, or the ID of the data
block containing the result. ERROR is usually error flags.
9 DATA TRANSMISSION - SNDPIC
The data transmission subroutines pass data between the two
computers. The calling program must specify the address where
transmission is to start. The address is used instead of the ID
since these subroutines do not communicate with MON11 and, therefore,
have no way of finding out what the address of an ID is. Neither do
they have any way of checking the addresses given them for validity.
Remember, if you create a new data block, and there are any deleted
data blocks around, the addresses of previously created blocks may no
longer be valid and FNDBLK should be called to verify them. It is
suggested that if you are going to be using a collection of data
blocks of fixed sizes, you create all of them before executing any
commands, and then fill and refill them as required. As long as you
do not delete any of them the addresses will not change. The
addresses of blocks created before any deleted blocks will never
change either.
DECLARATION: EXTERNAL PROCEDURE SNDPIC(INTEGER ADDR; BOOLEAN HOLD;
INTEGER TOP, BOTTOM, LEFT, RIGHT);
This subroutine sends a TV picture as defined by TVWORD and
the TV control words to the 11. BITS, LLINE, FLINE, LSIDE, and RSIDE
are used by SNDPIC. ADDR is the 11 address of the first word of the
data block which is to contain the picture. No check is made to
insure that the address is correct, or that the block is long enough.
TOP, BOTTOM, LEFT, and RIGHT define a window in the picture, which
may be the entire picture, which will be sent to the 11. Any of the
limits of the window which are outside the limits of the picture will
be set to the picture limit. The number of words needed for the
picture is:
8+(BOTTOM-TOP+1)*(RIGHT-LEFT+BYTE)/BYTE
where BYTE is 4 if BITS≤4 and 2 if 4<BITS≤8. Be warned that some
commands cannot process pictures with BITS>4. If HOLD is TRUE, MON11
will not be allowed to run while the transfer is taking place; if it
is FALSE, MON11 can run between each word transfered. The subroutine
does not return until the transfer is finished.
10 PUTBLK, GETBLK, GETWRD, PUTWRD
DECLARATION: EXTERNAL PROCEDURE PUTBLK(INTEGER A11,A10,CNT,HOLD)
EXTERNAL PROCEDURE GETBLK(INTEGER A11,A10,CNT,HOLD)
PUTBLK sends a block of data from the 10 to the 11 . GETBLK
gets a block of data from the 11. A11 is the starting address in the
11, as returned to you by the FNDBLK or BLKCOM commands. A10 is the
starting address in the 10. Note that if you want to use array
FOO[1:CNT], you should pass as A10 the expression LOCATION(FOO[1])
instead of just FOO[1], since it is not call by reference. CNT is the
number of words to transfer. HOLD is TRUE to hold the 11's memory as
explained for SNDPIC. Again, no checking of address validity or block
size is done. These subroutines are used to fill data blocks,other
than those containing pictures, and to get the results of command
execution from the 11. Note that A11 does not have to be the first
word of the data block. You can transfer parts of blocks, but note
the warning below.
* * * * * * * * * * * * *
DECLARATION: EXTERNAL INTEGER PROCEDURE GETWRD(INTEGER ADDR);
EXTERNAL PROCEDURE PUTWRD(INTEGER ADDR,WORD);
These procedures transmit one word of data to or from
location ADDR in the 11. GETWRD gets one word and returns it as its
value. PUTWRD sends WORD to the 11. They are useful for changing a
single word of a data block containing command arguments, where the
rest of the arguments can be used by many executions of the command
and for checking the progress of commands which keep updating the
same data block on successive calls.
WARNING: If you call any of the above routines with an 11 address
which is not the address returned by one of the monitor commands, you
must be aware that the 11 addresses used are byte addresses, where
there are two bytes per word. Thus if the starting address of your
data block (word 1) is stored in FOO and you want to get the nth word
of the data block, GETWRD(FOO+n-1) will lose; you must say
GETWRD(FOO+(n-1)*2).
11 ERRORS - INTERFACE AND PDP-11
INTERFACE ERRORS
All of these subroutines use the 10/11 hardware interface. If
they have difficulties with it, they will try several times and, if
they keep losing, will finally give up with one of the following error
messages:
Parity error for PDP11
Interface is transmiting bad parity.
PDP11 is halted.
The 11 has stopped. Check its console TTY for an error.
PDP11 UNIBUS does not respond
The 11 refuses to talk to the interface
cannot gain control of UNIBUS
The interface cannot get control of 11. Some other device has
hold of the 11's memory and will not release it.
After any of these messages, you are given the option of an automatic
restart of the 11 (see the INIT11 command). You should also check
the 11's console TTY for error messages.
* * * * * * * * * * * * * * *
PDP 11 ERRORS
Error messages of the following form may appear on the 11's console
TTY, causing MON11 to halt. Please inform me of their contents if
they occur:
ERROR TRAP OCCURED AT xxxxxxx
ILLEGAL INSTRUCTION TRAP OCCURED AT xxxxxxx
12 SPS-41 ERRORS
The SPS-41 causes only one error; refusing to terminate. The
11 programs will wait a while for a response and then type, on the
11's console TTY, the message:
DWELL LOOPING - xxxxxxxxxxxx
where the x's give the position of the problem in MON11. It will
follow the above message with:
TYPE C TO CONTINUE WAITING, R TO RESTART SPS-41
If you type C, on the 11's console TTY, it will wait again, and
return the same messages if there still is no response. If the
SPS-41 seems to always give this message for something you ask it to
do, and eventually terminates, tell me and I will make the wait
period longer. If you type R at it, the SPS-41 will be reinitialized
and the last task given it will be restarted, unless the
documentation for the user command you were performing says that it
cannot restart.
13 USER COMMANDS
Below is the documentation on implemented user commands.
Until a monitor is written which allows the user to load programs
into it from the 10, the only programs available are those built into
the monitor. Since these programs tend to be large, and the 11
memory is currently rather small, there will probably develop several
versions of the monitor, each containing the data structure
manipulation routines, and one or more user commands. Therefore, with
each command added to the list below will be indicated the name of
the BIN file containing the monitor to be used, on line MONITOR.
Substitute that name for MON11 throughout this document and you have
the documentation for that version. Each version of the monitor will
type out the file name on the 11's console TTY when it is started.
COMMAND # is the integer you give SNDCOM to execute the command,
ARGUMENT is the argument to SNDCOM. DATA and ERROR are the
quantities returned in those parameters of COMRET.
14 TRACK FEATURES
COMMAND: track a set of features between two images
Given two images and a set of feature coordinates for the
first, this command finds the coordinates of the same features in the
second image by applying a correlation operator to the areas of the
second picture where the features are predicted to be.
COMMAND #: 5
MONITOR: MON11C
ARGUMENT: ID of a control data block with a 10 element list:
1 ID of data block containing the first picture
2 ID of data block containing the second picture
3 ID of data block containing features
4 width of window for operator
5 length of window for operator
6 absolute value of limit of shift along X axis
7 absolute value of limit of shift along Y axis
8 shift increment (non-zero)
9 non-zero for debugging each correlation
10 non-zero for debugging best correlation
The feature data block contains 2 words of header data:
1 the number of features whose data follows
2 in debugging modes this word contains the number of
the feature last processed, which is the only one
whose data has changed since the last debugging
return.
Following the header data are nine words of data for each
feature, one after another, containing the following:
1 the X coordinate of the feature in the first image
specified by the upper left corner of a window which
is approximately centered on the feature
2 the Y coordinate of the feature in the first image
3 the user should set this to the value in 1 before
processing the first pair of images. This will be
updated as the program runs to be the X coordinate of
the feature in the last image processed. In debug-
ging returns, this is the window the current data is
for.
17 TRACK FEATURES (cont.)
4 the user should set this to the value in 2 before
processing the first pair of images. This is the Y
coordinate to go with 3
5 should be set non-zero before the first picture. It
will be cleared when the window goes outside of the
current picture, to indicate that it will no longer
be tracked.
6 the best correlation score for this feature in the
latest image is put here. For correlation debugging,
this will be the score for the current correlation.
7 the second best score is put here. It is not updated
for correlation debugging.
8 this and 9 should be cleared before the first image.
They are updated after each image to contain the
shift in the feature's position from the previous
image. They are used for predicting. This is X.
9 This is Y.
LIMITATIONS: The window must have at least 3 points per line, more
than 7 points in the window, and not more than 256 points in the
window. Only four bit images can be processed. Only this last
condition is tested by the command.
DATA: No data address is returned. All output is contained in the
above feature data block.
ERROR: error numbers decoded as follows: (only one error will be
detected);
-2 debugging output for best correlation being returned.
If requested, this will be returned once for each
feature in each image. The 11 will enter a wait loop.
Calling SNDCOM again will allow MON11A to continue,
but be sure you have the data in the 10 by then.
-1 same as -2 except returns after every correlation.
0 no errors - tracking is finished for this image
1 control block not found
2 picture 1 does not exist
3 picture 2 does not exist
4 feature data block does not exist
5 BITS>4 for one of the pictures